[[PageOutline(3-4, Sections)]]

== !TryUploadSubtitles == 

=== Intro ===

  try to upload subtitles, perform pre-upload checking (i.e. check if subtitles already exist on server)


----
=== Description ===

  '''struct !TryUploadSubtitles(string $token, struct('cd1' => struct('subhash' => string $submd5hash, 'subfilename' => string $subfilename, 'moviehash' => string $moviehash, 'moviebytesize' => string double $moviesize, 'movietimems' => int $movietimems, 'movieframes' => int $movieframes, 'moviefps' => double $moviefps, 'moviefilename' => string $moviefilename) $subfile, 'cd2' => struct(...) $subfile) $subs)'''

  This function is used to perform pre-upload checking on given subtitle files ''subfiles''. It will check if given subtitles are well-formed, if they already exist on the server, etc.

  This must be called '''before''' [wiki:XmlRpcUploadSubtitles UploadSubtitles()].
  
  It takes 2 parameters. First is the session token, second is a structure of information for subtitles to be uploaded, minimum ''cd1'' (one subtitle file) is required.
  
  The function returns ''alreadyindb'' = 1 when subtitles already exist in the database.
  
  When they do not exist, [wiki:XmlRpcSearchSubtitles SearchSubtitles()] is called and API tries to find existing subtitles based on ''moviehash/moviebytesize''. If some results are found, information is returned in ''data'' key as [wiki:XmlRpcSearchSubtitles SearchSubtitles()] return structure.
  This is good for uploading - user should have imdbid field already filled.


----
=== Parameters ===

  Parameters structure:
  {{{
  struct(
    (string) [token],
    struct(
      struct(
        (string) [subhash],
        (string) [subfilename],
        (string) [moviehash],
        (double) [moviebytesize],
        (int)    [movietimems],
        (int)    [movieframes],
        (double) [moviefps],
        (string) [moviefilename]
      ) [cd1],
      struct(
        ... same structure as cd1 ...
      ) [cd2],
      ... more subtitle file structures go here (if any) ...
    )
  )
  }}}

  ''token (required)''::
    token string identifying user's session, taken from [XmlRpcLogIn LogIn] output structure.
  ''subs''::
    structure of subtitle file information, contains one or more ''subfile'' structures
    ''subfile''::
      * structure containing information about one subtitle file
      * mandatory fields are: ''subhash'', ''subfilename'', ''[wiki:HashSourceCodes moviehash]'', ''moviebytesize'', ''moviefilename''.
      * ''subhash'': MD5 hash of subtitle file contents
      * ''subfilename'': subtitle filename      
      * ''moviehash'': hash calculated for the video file contents, see ''[wiki:HashSourceCodes Hash Source Codes]'' for various implementations
      * ''moviebytesize'': size of video file in bytes
      * ''movietimems'': length of video in miliseconds
      * ''movieframes'': length of video in frames
      * ''moviefps'': frame rate used in video file, e.g. 23.976
      * ''moviefilename'': video filename


----
=== Return Values ===

  Output is returned in this structure: 
{{{
  struct(
    (string) [status],
    (int)    [alreadyindb],
    array(
      struct(  <--- this is the usual subtitle file structure
        (string) [IDMovieImdb],
        (string) [MovieName],
        (string) [MovieYear],
        (string) [MovieHash],
        (string) [MovieReleaseName],
        (string) [IDMovie],
        (string) [MovieNameEng]
        (string) [MovieImdbRating],
        
        + 2 extra indicator fields:
        (string) [MoviefilenameWasAlreadyInDb]
        (string) [HashWasAlreadyInDb]
        
      ) [subfile]
    ) [data]
    (double) [seconds]
  )
}}}

  and contains these elements:
    ''status''::
      function result code, see [XmlRpcStatusCode list of status codes]
    ''alreadyindb''::
      * indicator if subtitles are already available on the server.
      * '''1''' if they are (upload should be interrupted, duplicate subtitle), 
      * '''0''' if they're not (upload can continue)
    ''data''::
      * this array will contain one subtitle file structure (if found),
      * this structure can be used to automatically gather information about movie,
      * e.g. get IMDb ID so the user doesn't have to input it manually.
    ''subfile''::
      * informational subtitle file structure 
      * see [wiki:XmlRpcStruSubFile subtitle file structure].
      * ''!HashWasAlreadyInDb'' - 0 means new ''moviehash'' was inserted into the database.
      * ''!MoviefilenameWasAlreadyInDb'' - 0 means new ''moviefilename'' was inserted into the database.
    ''seconds''::
      time taken to execute this command on server


----
=== Implementations ===

  There are currently no available sample implementations.


----
=== Changelog ===

  Version 1: created this function


----
=== Examples ===


==== Input ====
  
{{{
#!xml
<methodCall>
 <methodName>TryUploadSubtitles</methodName>
 <params>
  <param>
   <value><string>d5pnounn3ea5aja0nn4inqamf2</string></value>
  </param>
  <param>
   <value>
    <struct>
     <member>
      <name>cd1</name>
      <value>
       <struct>
        <member>
         <name>subhash</name>
         <value><string>ebe86f4a0357d8c1d635ec49f77e27d6</string></value>
        </member>
        <member>
         <name>subfilename</name>
         <value><string>almost.heros.1998.dvdrip.xvid.fragment.cze.srt</string></value>
        </member>
        <member>
         <name>moviehash</name>
         <value><string>89ceb12ab48e3b1f</string></value>
        </member>
        <member>
         <name>moviebytesize</name>
         <value><double>731508736</double></value>
        </member>
        <member>
         <name>moviefps</name>
         <value><double>23.976</double></value>
        </member>
        <member>
         <name>movietimems</name>
         <value><int>5413204</int></value>
        </member>
        <member>
         <name>movieframes</name>
         <value><int>129787</int></value>
        </member>
        <member>
         <name>moviefilename</name>
         <value><string>almost.heros.1998.dvdrip.xvid.fragment.avi</string></value>
        </member>
       </struct>
      </value>
     </member>
     ... more subtitle files go here (if any, e.g. for cd2, etc.) ...
    </struct>
   </value>
  </param>
 </params>
</methodCall>
}}}

  
==== Output ====

{{{
#!xml
<methodResponse>
 <params>
  <param>
   <value>
    <struct>
     <member>
      <name>status</name>
      <value><string>200 OK</string></value>
     </member>
     <member>
      <name>alreadyindb</name>
      <value><int>0</int></value>
     </member>
     <member>
      <name>data</name>
      <value>
       <array>
        <data>
         <value>
          <struct>
           <member>
            <name>IDMovieImdb</name>
            <value><string>119053</string></value>
           </member>
           <member>
            <name>MovieName</name>
            <value><string>Almost Heroes</string></value>
           </member>
           <member>
            <name>MovieYear</name>
            <value><string>1998</string></value>
           </member>
           <member>
            <name>MovieHash</name>
            <value><string>89ceb12ab48e3b1f</string></value>
           </member>
           <member>
            <name>MovieReleaseName</name>
            <value><string>Almost Heroes 1998 DVDRip XviD-FRAGMENT</string></value>
           </member>
           <member>
            <name>IDMovie</name>
            <value><string>13427</string></value>
           </member>
           <member>
            <name>MovieNameEng</name>
            <value><string>Almost History</string></value>
           </member>
           <member>
            <name>MovieImdbRating</name>
            <value><string>4.5</string></value>
           </member>

           ... the usual subtitle file structure continues, not important ...

          </struct>
         </value>
        </data>
       </array>
      </value>
     </member>
     <member>
      <name>seconds</name>
      <value><double>0.065</double></value>
     </member>
    </struct>
   </value>
  </param>
 </params>
</methodResponse>
}}}


----
=== Notes ===

  none yet


----
=== See also ===

  * [wiki:XmlRpcUploadSubtitles UploadSubtitles]


----
=== Comments ===

	add your comments, hints and suggestions here if you like ...



[Prev] [wiki:XmlRpcIntro Home] [wiki:XmlRpcUploadSubtitles Next]